# The following is a short synopsis of the menu file entities available for
# use in menu files.
#
# The general format of an entity in a menu is as follows:
#
#  entity_name name { attributes_and_values ... }
# 
# The following conventions are used in this document:
# 
#  o  Attributes are optional unless specified as being "Required".
#  o  Attributes that may be specified only once are indicated with "Once only".
#  o  Attribute value keyword choices are separated by vertical bars,
#     e.g. "choice1 | choice2".
#  o  Other attribute values are shown in CAPS.
#  o  Optional names and attribute values are enclosed in square brackets ([]).
#  o  Names must begin with a character or an underscore and may include
#     characters, digits, and underscores.  Names are used for referencing
#     one entity from another.
#  o  Comments begin with a pound sign (#) and continue to the end of the line.
#  o  The menu system file format is free form.  Newlines and whitespace are
#     ignored.  String values containing spaces must be enclosed within quotes
#     ("") or apostrophes ('').



menu_handler VERSION  {  # The current version is "2".

 units X Y  # Once only.  Defines the x and y units used for sizing windows
            # and menu items.  The number of pixels in a unit is calculated as:
            #  xunit = no. horizontal pixels on monitor / X
            #  yunit = no. vertical   pixels on monitor / Y
            # xunit and yunit default to 1 pixel if this attribute is not
            # specified.

 top_screen SCREEN_NAME  # Once only.  Name of the first screen to display.
                         # Defaults to the first screen encountered.

 color_table { ... }  # Once only.  Color table definition.  See below.

 window NAME { ... }  # Window definition.  See below.  NAME is required
                      # when window is defined here.

 screen [NAME] { ... }  # Screen definition.  See below.

 group NAME { ... }  # Menu item group definition.  See below.  NAME is
                     # required when group is defined here.

 MENU_ITEM_TYPE_NAME NAME { ... }  # Menu item definition.  See below.  NAME
                                   # is required when item is defined here.
}



color_table {  # Color table.

 COLOR_NAME RED GREEN BLUE  # Color definition.  Red, green, and blue values
                            # are specified as floating point numbers between
                            # 0.0 and 1.0 inclusive.  The color may then be
                            # referenced by name in menu item definitions.
}



window [NAME] {  # Menu window.

 parent NAME  # This window's parent window.  If the window is to be parented
              # by the window manager's root window, this attribute should not
              # be specified.

 title STRING  # This title will be displayed on the window manager's border if
               # the window is parented by the manager's root window.

 origin X Y  # Window origin in x and y units.  Defaults to (0, 0).

 size X Y  # Required.  Window size in x and y units.

 background_color NAME  # Window background color.  Defaults to black.

 border_width WIDTH  # Width in pixels of the window's border.  The border
                     # will not be drawn if set to 0.  Default is 0.

 border_color NAME  # Window border color.  Defaults to black.

 buffering single | double  # Single or double buffering.  Defaults to single.
}



screen [NAME] {  # A screen contains a set of menus to be displayed
                 # concurrently.

 menu [NAME] { ... }  # Menu definition.  See below.

 menu NAME            # Menu reference.
}



group [NAME] {  # A group contains a set of menu items.  Groups are
                   # referenced by frames, menus, and popup menus.

 units X Y  # Once only.  Defines the x and y units used for sizing menu items
            # in this group.  The number of pixels in a unit is calculated as:
            #  xunit = no. horizontal pixels in window / X
            #  yunit = no. vertical   pixels in window / Y
            # xunit and yunit default to the x and y units defined under
            # menu_handler (see above) if this attribute is not specified.
            # The window used in the calculation is the window associated
            # with the menu item containing this group.

 MENU_ITEM_TYPE_NAME [NAME] { ... }  # Menu item definition.  See below.

 MENU_ITEM_TYPE_NAME NAME            # Menu item reference.
}



# The remainder of this document show the available menu item types and their
# attributes.



frame [NAME] {  # A frame contains a group of other menu items and give them
                # position information.

 position X Y  # Expressed in x and y units.  Defaults to (0, 0).

 size X Y  # Required.  Expressed in x and y units.
 group [NAME] { ... }  # Required.  The group of menu items contained by
 # or                  # this frame.  The group may be referenced by name
 group NAME            # or defined here.  See above.
 active STRING  # A key that is passed to a lookup function that determines
                # if the items in this frame are active.
}



menu [NAME] {  # A menu contains a group of other menu items and specifies
               # the window to display them in.  Menus are referenced by
               # screens (see above).

 group [NAME] { ... }  # Required.  The group of menu items contained by
 # or                  # this menu.  The group may be referenced by name
 group NAME            # or defined here.  See above.

 window [NAME] { ... }  # Required.  The window used for displaying the
 # or                   # menu items.  The window may be referenced by name
 window NAME            # or defined here.  See above.
}



popmenu [NAME] {  # A popup menu contains a group of other menu items and
                     # specifies the window to display them in.  Popup menus
                     # are opened by popup buttons (see below).

 group [NAME] { ... }  # Required.  The group of menu items contained by
 # or                  # this menu.  The group may be referenced by name
 group NAME            # or defined here.  See above.

 window [NAME] { ... }  # Required.  The window used for displaying the
 # or                   # menu items.  The window may be referenced by name
 window NAME            # or defined here.  See above.

 mode temporary | permanent | dialog  # Specifies the popup menu's mode:
                                      #  temporary - The popup menu becomes
                                      #   a part of the current screen.
                                      #  permanent - The popup menu is managed
                                      #   by the menu handler and remains even
                                      #   if the screen is changed.
                                      #  dialog - The popup menu locks out
                                      #   interaction with all other menus.
                                      # Temporary mode is the default if this
                                      # attribute is not specified.
}



label [NAME] { # A label displays text.

 position X Y  # Expressed in x and y units.  Defaults to (0, 0).

 size X Y  # Required.  Expressed in x and y units.

 rect_color NAME  # Background rectangle color.  Defaults to "body".

 text STRING  # Text to be displayed.

 text_color NAME  # Text color.  Defaults to "label_text".

 text_offset X Y  # Text offset from upper-left corner, expressed in x and y
                  #  units.  Defaults to (0, 0).

 active STRING  # A key that is passed to a lookup function that determines
                # if the item is active.

 display STRING  # A key that is passed to a lookup function that returns the
                 # text to be displayed.
}



button [NAME] {  # A button executes a command.

 position X Y  # Expressed in x and y units.  Defaults to (0, 0).

 size X Y  # Required.  Expressed in x and y units.

 rect_color NAME  # Background rectangle color.  Defaults to "body".

 text STRING  # Text to be displayed.

 text_color NAME  # Text color.  Defaults to "button_text".

 text_offset X Y  # Text offset from upper-left corner, expressed in x and y
                  #  units.  Defaults to (0, 0).

 selected_color NAME  # Selected text color.  Defaults to "selected_text".

 screen [NAME] [ { ... } ]  # Screen to be loaded.  See above.  Screen may
                            # be referenced by name only or defined here.

 popmenu [NAME] [ { ... } ]  # Popup menu to be opened.  See above.  Popup
                             # menu may be referenced by name only or
                             # defined here.

 command STRING  # Command to execute.

 active STRING  # A key that is passed to a lookup function that determines
                # if the item is active.

 display STRING  # A key that is passed to a lookup function that returns the
                 # text to be displayed.

 help STRING  # A key that is passed to the help processor that displays help
              # on this item's command.
}



toggle [NAME] {  # A toggle button indicates a boolean state and executes
                 # one of two commands determined by its state.

 position X Y  # Expressed in x and y units.  Defaults to (0, 0).

 size X Y  # Required.  Expressed in x and y units.

 rect_color NAME  # Background rectangle color.  Defaults to "body".

 text STRING  # Text to be displayed.

 text_color NAME  # Text color.  Defaults to "button_text".

 text_offset X Y  # Text offset from upper-left corner, expressed in x and y
                  #  units.  Defaults to (0, 0).

 selected_color NAME  # Selected text color.  Defaults to "selected_text".

 screen [NAME] [ { ... } ]  # Screen to be loaded.  See above.  Screen may
                            # be referenced by name only or defined here.

 popmenu [NAME] [ { ... } ]  # Popup menu to be opened.  See above.  Popup
                             # menu may be referenced by name only or
                             # defined here.

 true_command STRING  # Command to execute if state is true.

 false_command STRING  # Command to execute if state is false.

 toggle STRING  # A key passed to a lookup function that determines the
                # toggle's state.

 active STRING  # A key that is passed to a lookup function that determines
                # if the item is active.

 display STRING  # A key that is passed to a lookup function that returns the
                 # text to be displayed.

 help STRING  # A key that is passed to the help processor that displays help
              # on this item's commands.
}



oneonly [NAME] {  # A oneonly button indicates a boolean state and executes
                  # a command.  Oneonlys are usually grouped together to
                  # indicate a choice of one amongst many.

 position X Y  # Expressed in x and y units.  Defaults to (0, 0).

 size X Y  # Required.  Expressed in x and y units.

 rect_color NAME  # Background rectangle color.  Defaults to "body".

 text STRING  # Text to be displayed.

 text_color NAME  # Text color.  Defaults to "button_text".

 text_offset X Y  # Text offset from upper-left corner, expressed in x and y
                  #  units.  Defaults to (0, 0).

 selected_color NAME  # Selected text color.  Defaults to "selected_text".

 screen [NAME] [ { ... } ]  # Screen to be loaded.  See above.  Screen may
                            # be referenced by name only or defined here.

 popmenu [NAME] [ { ... } ]  # Popup menu to be opened.  See above.  Popup
                             # menu may be referenced by name only or
                             # defined here.

 command STRING  # Command to execute.

 oneonly STRING  # A key passed to a lookup function that determines the
                 # oneonly's state.

 active STRING  # A key that is passed to a lookup function that determines
                # if the item is active.

 display STRING  # A key that is passed to a lookup function that returns the
                 # text to be displayed.

 help STRING  # A key that is passed to the help processor that displays help
              # on this item's command.
}



roller [NAME] {  # A roller button indicates a state of one amongst many and
                 # executes commands based on its state.

 position X Y  # Expressed in x and y units.  Defaults to (0, 0).

 size X Y  # Required.  Expressed in x and y units.

 rect_color NAME  # Background rectangle color.  Defaults to "body".

 nvalues INTEGER  # Number of states.

 texts STRING1, ... STRINGn  # Texts to be displayed based on the state.

 text_color NAME  # Text color.  Defaults to "button_text".

 text_offset X Y  # Text offset from upper-left corner, expressed in x and y
                  #  units.  Defaults to (0, 0).

 selected_color NAME  # Selected text color.  Defaults to "selected_text".

 screen [NAME] [ { ... } ]  # Screen to be loaded.  See above.  Screen may
                            # be referenced by name only or defined here.

 popmenu [NAME] [ { ... } ]  # Popup menu to be opened.  See above.  Popup
                             # menu may be referenced by name only or
                             # defined here.

 commands STRING1, ... STRINGn  # Commands to execute based on the state.

 roller STRING  # A key passed to a lookup function that determines the
                # roller's state.

 active STRING  # A key that is passed to a lookup function that determines
                # if the item is active.

 display STRING  # A key that is passed to a lookup function that returns the
                 # text to be displayed.

 help STRING  # A key that is passed to the help processor that displays help
              # on this item's commands.
}



prevscreen [NAME] {  # A prevscreen button pops the current screen off
                        # the stack.

 position X Y  # Expressed in x and y units.  Defaults to (0, 0).

 size X Y  # Required.  Expressed in x and y units.

 rect_color NAME  # Background rectangle color.  Defaults to "body".

 text STRING  # Text to be displayed.

 text_color NAME  # Text color.  Defaults to "button_text".

 text_offset X Y  # Text offset from upper-left corner, expressed in x and y
                  #  units.  Defaults to (0, 0).

 selected_color NAME  # Selected text color.  Defaults to "selected_text".

 levels INTEGER  # Number of _additional_ screens to pop off the stack.
                 # Defaults to 0.
}



topscreen [NAME] {  # A topscreen button pops all but the top screen off
                       # the stack.

 position X Y  # Expressed in x and y units.  Defaults to (0, 0).

 size X Y  # Required.  Expressed in x and y units.

 rect_color NAME  # Background rectangle color.  Defaults to "body".

 text STRING  # Text to be displayed.

 text_color NAME  # Text color.  Defaults to "button_text".

 text_offset X Y  # Text offset from upper-left corner, expressed in x and y
                  #  units.  Defaults to (0, 0).

 selected_color NAME  # Selected text color.  Defaults to "selected_text".
}



popdown [NAME] {  # A popdown button executes a command and removes the
                  # popup menu it belongs to.

 position X Y  # Expressed in x and y units.  Defaults to (0, 0).

 size X Y  # Required.  Expressed in x and y units.

 rect_color NAME  # Background rectangle color.  Defaults to "body".

 text STRING  # Text to be displayed.

 text_color NAME  # Text color.  Defaults to "button_text".

 text_offset X Y  # Text offset from upper-left corner, expressed in x and y
                  #  units.  Defaults to (0, 0).

 selected_color NAME  # Selected text color.  Defaults to "selected_text".

 command STRING  # Command to execute.

 active STRING  # A key that is passed to a lookup function that determines
                # if the item is active.

 display STRING  # A key that is passed to a lookup function that returns the
                 # text to be displayed.

 help STRING  # A key that is passed to the help processor that displays help
              # on this item's command.
}



list [NAME] {  # A list displays rows of menu items and provides a scrollbar.

 position X Y  # Expressed in x and y units.  Defaults to (0, 0).

 size X Y  # Required.  Expressed in x and y units.

 nvisible INTEGER  # Number of rows of menu items to display.  Defaults to 1.

 ntotal INTEGER  # Total number of rows in the list (if known).

 ntotalkey STRING  # A key that is passed to a lookup function that returns the
                   # total number of rows in the list.

 space INTEGER  # Number of yunits between rows.  Defaults to 0.

 scroll {
  position X Y  # Expressed in x and y units.  Defaults to (0, 0).

  size X Y  # Required.  Expressed in x and y units.

  step_buttons  # Specifies that the scroll bar will have single-step buttons
                # present.
 }

 MENU_ITEM_TYPE_NAME [NAME] { ... }  # Menu item definition.  See above.  May
 # or                                # be referenced by name or defined here.
 MENU_ITEM_TYPE_NAME NAME            # The menu items specified represent one
                                     # row of the list.  These items are
                                     # duplicated as many times as necessary
                                     # to fill out the number of rows specified
                                     # with nvisible.
}



browser [NAME] {  # File browser.

 position X Y  # Expressed in x and y units.  Defaults to (0, 0).

 size X Y  # Required.  Expressed in x and y units.

 nvisible INTEGER  # Number of rows of directories and files to display.
                   #  Defaults to 10.

 select_files true | false  # Specifies whether or not files are selectable.
                            # Defaults to "true".

 directory STRING  # Initial directory.

 filter STRING  # Initial filter.

 cancel_action  none | return | popdown | exit  # Action performed by the
                                                # the cancel button:
                                                #  none - does nothing
                                                #  return - acts like a
                                                #   prevscreen button
                                                #  popdown - acts like a
                                                #   popdown button
                                                #  exit - causes the program
                                                #   to exit

 ok_action  none | return | popdown | exit  # Action performed by the
                                            # the ok button after executing
                                            # the browser's action:
                                            #  none - does nothing
                                            #  return - acts like a
                                            #   prevscreen button
                                            #  popdown - acts like a
                                            #   popdown button
                                            #  exit - causes the program
                                            #   to exit
}


--------------------------------------------------------------------------------
Some comments from Steve about menu system's "set" command
--------------------------------------------------------------------------------
o "set var value" is used in several places in the menu files
  already.  Just do a "grep '^ *set *\$' *.ms" to find out where.
  (I always precede the variable name with a '$' just to make the
  name more unique and easier to find.)
 
  Menu system variables are global in scope, but you must invoke
  a special (i.e. clumsy) mechanism to dereference them.  Vari-
  ables can be dereferenced in command strings, lookup strings,
  and text strings.  (There may be other places, but these are
  the most important.)  For example:
 
    set $view 0
    ...
    text "VIEW $view COMMANDS" ($view)
 
  The "($view)" tells the menu system that it should search the
  previous string for "$view" and replace it with its current
  value.  Multiple variables can be used in a single string as in
 
    text "VIEW $view LIGHT $light" ($view, $light)
 
  There are a couple of ways to pass in variable values to the
  menu system.  The first is to use the menu system reader pre-
  processor:
 
    mentat ... -D ppvarname=value
 
  I think this is the correct syntax; check in_interface::
  initialize.  This defines a preprocessor variable and is
  equivalent to having the following in a menu file:
 
    #define ppvarname value
  To get the preprocessor variable value into a menu system
  variable, use the set construct:
 
    set msvarname ppvarname
 
  Menu system variables can also be set through a menu system
  method (see ms_handler.h):
 
    ms_handler &set(const ut_string &name,
                    const ut_string &value);
    ms_handler &set(ms_param *param,
                    const ut_string &value);
 
  The disadvantage of this is that you have to have access to the
  menu system, which may not be appropriate in certain parts of
  the program.
 

--------------------------------------------------------------------------------
